home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / uw_1.exe / ENQHELP.DOC < prev    next >
Text File  |  1992-11-10  |  14KB  |  244 lines
  1. ------------------------ Using the EnQue Help Engine ----------- 11/10/92 --
  2.  
  3.     This file is divided into two parts.  The first describes how to use the
  4. help engine.  The second describes how to create your own help files.
  5.  
  6.   The help engine is very easy to use due to its employment of EnQue's new
  7. user-interface construction program, the TUICP.  The help may be used with
  8. either the keyboard or mouse.  To make composing your own help easy, the
  9. engine uses simple ASCII files.  These files can contain text commands to
  10. allow for color control, hypertext links, sound, and much more.  If the
  11. files exist in the current directory, those files are accessed, otherwise,
  12. the help engine looks in the path set by the environment variable ENQHELP.
  13. To set this, add a line like "SET ENQHELP=C:\BORLANDC\ENQUE" to your
  14. AUTOEXEC.BAT file.
  15.  
  16.   To invoke the ENQHELP.EXE stand alone help engine, type:
  17.   
  18.   ENQHELP FILENAME.EXT GET_MODE SEARCH_STR SX SY EX EY
  19.   
  20. where FILENAME.EXT is the first file the help engine should access, the
  21. GET_MODE (0 or 1) parameter tells the help engine to read the characters
  22. underneath the cursor and search for that keyword, and SEARCH_STR is an
  23. optional search string.  If you simply wish the help engine to display the
  24. beginning of the file, use 0 for both GET_MODE and SEARCH_STR.  The SX, SY,
  25. EX and EY parameters specify the upper-left and lower-right corners for the
  26. help window.  Default values of 0, 0, 79, and 24 will be used if no
  27. parameters are specified.  The help window must be either wider than 64
  28. characters, or taller than 14. This is to allow for the dialog interface
  29. buttons and sliders.  If the values are out of range or the file does not
  30. exist, the help engine will return.  The help engine can be invoked with no
  31. parameters and will act as if you had typed
  32.                "ENQHELP UW_HELP0.HLP 0 0 0 0 79 24".
  33.  
  34.     If you wish to use ENQHELP.EXE from within Borland's compilers, you may
  35. set it up as a Transfer program.  This allows you to pull up help for all
  36. UltraWin functions.  See "Setting up a transfer program" below.
  37.  
  38.   Once active, you can scroll around the help file much like an editor.
  39. UP, DOWN, LEFT, RIGHT, HOME, END, PgUp, PgDn, Ctrl-PgUp, and Ctrl-PgDn
  40. allow you to move around the file.  If the file is wider than the help
  41. window you can scroll horizontally as well as vertically.
  42. The buttons operate as follows:
  43.  
  44. Search   - [Alt-S] allows you to search for a specific word or phrase.
  45. Repeat   - [Alt-R] finds the next occurrence specified by Search.
  46. <<<      - [Shift-Tab] moves to the previous keyword.
  47. >>>      - [Tab]  moves to the next keyword.
  48. Previous - [Alt-P] moves to the previously active keyword.
  49. Index    - [Alt-I] moves to the original starting place.
  50. Quit     - [Alt-Q] exits the help program.
  51.  
  52.     If you are using a mouse, clicking on the button, sliders, close box,
  53. (upper left corner), or keyword will activate the function.
  54.  
  55.   To move to a keyword, you can use the tab or cursor keys.  The keyword
  56. will change colors.  Pressing [Enter] or double clicking on this word will
  57. take you to additional information on this topic.  Pressing [Alt-P]
  58. (previous) will take you back one level.
  59.  
  60.     To search for a specific word/phrase, press [Alt-S] or click on Search.
  61. This pulls up a dialog box.  To enter the word/phrase, press [Alt-S] again
  62. or click on the string following the word Search.  Type in the word/phrase
  63. and press [Alt-O] or click on OK.  The default search will proceed forward
  64. from the current cursor location.  The direction and scope can be changed by
  65. clicking on the appropriate check box or pressing the desired hot-key.
  66.  
  67. Forward   - [Alt-F] sets the search direction to forwards.
  68. Backward  - [Alt-B] sets the search direction to backwards.
  69. From Csr  - [Alt-R] searches from current cursor position.
  70. Global    - [Alt-G] searches from the start of file.
  71. Case      - [Alt-C] sets the case sensitivity.
  72. Quit      - [Alt-Q] quits from the search dialog.
  73. OK        - [Alt-O] accepts the parameters and finds the first word. 
  74.  
  75.  
  76. SETTING UP A TRANSFER PROGRAM
  77. -----------------------------
  78.   To use the help engine as a transfer program for the Borland Compilers,
  79. edit the transfer parameters as normal (see the Borland documentation) and
  80. for the command line parameters be sure to type $NOSWAP as the first
  81. command.  An example for an EGA 43 row screen would be "$NOSWAP UW_HELP0.HLP
  82. 1 0 1 15 78 40".  If you would like the help engine to "move" directly to
  83. the function underneath the cursor, load the tiny TSR TCKBD.COM before
  84. entering the compiler.  This program keeps a copy of the last cursor column
  85. and row, so when the cursor is hidden on execution of the transfer program
  86. the engine will know the location of the search word.  It is a good idea to
  87. call TCKBD.COM form your AUTOEXEC.BAT file.
  88.  
  89.     Please note that the Borland compilers require you to set up the transfer
  90. program for each project file you create.
  91.   
  92.  
  93. WRITING YOUR OWN HELP FILES
  94. ---------------------------
  95.   The help commands are structured much like a "C" function call with a few
  96. restrictions.  The command must be preceded by a ` character, and no white-
  97. space is allowed within the command.  All commands are stripped from the
  98. help display.  A line within the help text file can contain multiple
  99. commands and can be up to 255 characters in length.  Keep in mind that the
  100. displayed width may be less since commands are stripped.  Also note that no
  101. commands are required, the help may simply consist of ASCII text that is
  102. linefeed or carriage return/linefeed delimited.  These commands are designed
  103. to allow you to enhance your help files and add powerful HyperText
  104. capabilities.  Since the help files are simply ASCII, they can be edited
  105. with virtually any text editor.  The help engine will accept and display the
  106. extended character set if desired and if your editor allows the inclusion of
  107. these characters.  This allows you to create borders, etc., within your help
  108. files.  The drawback to ASCII files is a small sacrifice in speed when
  109. reading/parsing these files.  However, by keeping your help files relatively
  110. small, (which they should be to conserve memory as much as for speed), this
  111. drawback is all but unnoticable.
  112.  
  113.  
  114. SPECIAL HELP COMMANDS
  115. ---------------------
  116.  
  117. KEYWORD:  `keyword(word,search string);
  118.   There are three forms of the keyword command.  The first specifies the 
  119. actual keyword followed by a search string.  Both the keyword and the search
  120. string can consist of several words (up to 80 characters).  In this form, 
  121. the search string must reside in the same file as the keyword command.  It
  122. can be located anywhere in the file and should be unique.  It is good
  123. practice to use a character or sequence of characters in the search string
  124. that will not commonly occur in the text in order to assure this uniqueness.
  125. For example `keyword(File System,/// The DOS File System);  Here we use
  126. three / to insure the uniqueness of the search string.  Note that the keyword
  127. and search string can be different.
  128.   The second form is like the first but includes a modifier in front of the
  129. search string.  This modifier, enclosed in brackets, specifies the file in
  130. which the search string exists.  For example, `keyword(DOS,[dos.hlp]/// DOS);
  131. This works the same as the example above except that the file dos.hlp will
  132. no be loaded into the help engine and the search string "/// DOS" will be
  133. located.
  134.   The third form is similar to the other two in form but different in action.
  135. When the user moves to this keyword and presses <Enter>, the second parameter
  136. is used as a DOS command and executed.  For example, `keyword(DIR,{dir c:});
  137. When selected, this keyword will execute the DOS command "dir c:".  This
  138. is useful for creating menus, shells, etc.
  139.  
  140. COLOR:  `color(foreground string,background string);
  141.   There are a number of color control commands that allow you to personalize
  142. your help files.  Often, only one or two are used.  The first and most common
  143. is the color command.  Two parameters specify the foreground and background
  144. colors.  For example `color(RED,LIGHTGRAY);  Sixteen c